Scripting
  • English
  • TestFlight

      • Use with Toolbar Component

      In Scripting, views can populate their navigation bar or toolbar area using either the original ToolBarProps object or the declarative component-based API that mirrors SwiftUI’s toolbar system. This document explains in detail how to use the Toolbar, ToolbarItem, ToolbarItemGroup, ToolbarSpacer, and DefaultToolbarItem components, including parameters, types, and usage patterns.

      Overview

      The toolbar property can be used in two ways:

      • By passing a ToolBarProps object
      • By passing a VirtualNode, which must be a <Toolbar> component

      When using the component-based API, all toolbar content is declared inside a <Toolbar> container, and each item defines its placement explicitly. This provides clearer structure and more precise layout control, similar to SwiftUI.

      <List toolbar={<Toolbar>{/* toolbar items here */}</Toolbar>}>{/* main content */}</List>

      Toolbar

      The <Toolbar> component serves as a container for toolbar content. It does not define placement itself; instead, ToolbarItem and ToolbarItemGroup determine where items go.

      Example

      <List
  toolbar={
    <Toolbar>
      <ToolbarItem placement="topBarLeading">
        <Button title="Close" action={dismiss} />
      </ToolbarItem>
      <ToolbarItem placement="topBarTrailing">
        <Button title="Done" action={handleDone} />
      </ToolbarItem>
    </Toolbar>
  }>
  {/* content */}
</List>

      ToolbarItem

      ToolbarItem represents a single toolbar element placed at a specific position.

      Parameters

      ParameterTypeDefaultDescription
      placementToolbarItemPlacementautomaticPosition of the item, such as topBarLeading, navigation, primaryAction
      childrenVirtualNoderequiredThe item’s content, usually a button or text

      Example

      <Toolbar>
  <ToolbarItem placement="navigation">
    <Button title="Back" action={Navigation.useDismiss()} />
  </ToolbarItem>
</Toolbar>

      ToolbarItemGroup

      ToolbarItemGroup allows multiple toolbar items to be grouped together in a single placement.

      Parameters

      ParameterTypeDefaultDescription
      placementToolbarItemPlacementautomaticPlacement for the entire group
      childrenmultiple VirtualNodesrequiredThe grouped toolbar items

      Example

      <Toolbar>
  <ToolbarItemGroup placement="topBarTrailing">
    <Button title="Refresh" action={reload} />
    <Button title="More" action={openMenu} />
  </ToolbarItemGroup>
</Toolbar>

      ToolbarSpacer

      ToolbarSpacer inserts empty space in a toolbar. It can be used to fine-tune layout between items.

      Parameters

      ParameterTypeDefaultDescription
      sizing'fixed' | 'flexible'flexibleDetermines whether the spacer expands or stays fixed
      placementToolbarItemPlacementautomaticPlacement for the spacer

      Behavior

      • flexible: Expands to fill available space.
      • fixed: Adds a fixed separation between items.

      Example

      <Toolbar>
  <ToolbarItem placement="topBarTrailing">
    <Button title="Edit" action={edit} />
  </ToolbarItem>

  <ToolbarSpacer sizing="fixed" />

  <ToolbarItem placement="topBarTrailing">
    <Button title="Save" action={save} />
  </ToolbarItem>
</Toolbar>

      DefaultToolbarItem

      DefaultToolbarItem inserts system-provided toolbar items, such as the sidebar toggle button or search button.

      Parameters

      ParameterTypeDefaultDescription
      kind"sidebarToggle" | "search" | "title"requiredSpecifies which system item to insert
      placementToolbarItemPlacementautomaticToolbar placement

      Example

      <Toolbar>
  <DefaultToolbarItem kind="search" placement="topBarTrailing" />
</Toolbar>

      Complete Example

      <NavigationStack>
  <List
    toolbar={
      <Toolbar>
        {/* Navigation button */}
        <ToolbarItem placement="navigation">
          <Button title="Back" action={Navigation.useDismiss()} />
        </ToolbarItem>

        {/* Title */}
        <DefaultToolbarItem kind="title" />

        {/* Trailing group */}
        <ToolbarItem placement="topBarTrailing">
          <Button title="Edit" action={edit} />
        </ToolbarItem>
        <ToolbarSpacer sizing="fixed" />
        <ToolbarItem placement="topBarTrailing">
          <Button title="Done" action={finish} />
        </ToolbarItem>

        {/* Bottom bar item */}
        <ToolbarItem placement="bottomBar">
          <Button title="Help" action={showHelp} />
        </ToolbarItem>
      </Toolbar>
    }>
    {/* content */}
  </List>
</NavigationStack>

      Relationship with ToolBarProps

      MethodDescription
      toolbar={{ topBarTrailing: <Button/> }}Simple and declarative for straightforward scenarios
      toolbar={<Toolbar>...</Toolbar>}More explicit, structured, and ideal for complex layouts

      Both approaches remain fully supported. When a VirtualNode is passed, it must be a <Toolbar> component to ensure proper layout interpretation.